home *** CD-ROM | disk | FTP | other *** search
/ Delphi Programmer's Power Pack / Delphi Volume 1.iso / s_to_z / w32filop / usage.txt < prev    next >
Text File  |  1996-09-15  |  6KB  |  146 lines
  1.  CALL32nt.pas: Library for Delphi/TPW/BPW to call 32 bit functions
  2.                in Windows NT or Windows 95
  3.  
  4. Adapted to Pascal by Christian Ghisler
  5. from CALL32.DLL, a DLL for Visual Basic 
  6. written and placed in the Public Domain by Peter Golde
  7.  
  8. This unit is placed in the public domain.
  9. Please feel free to redistribute as you wish.  
  10. No guarantees are made as to its suitability or
  11. usefulness, and no support can be provided.
  12.  
  13.  
  14. To call a function in a 32-bit DLL, follow these steps:
  15.  
  16.  1. Declare the function you wish to call. Declare it
  17.  in the ordinary fashion, with the following exceptions:
  18.  
  19.  >  Declare it as a function variable
  20.  >  Add an additional argument at the end, of type Longint:
  21.  
  22.  For example, if you are calling the function:  (C code)
  23.  
  24.     GetWindowText(HWND hwnd, LPSTR lpsz, int cch)
  25.  
  26.  declare it as follows (remember that ints and all handles
  27.  are 32 bits, so use a Longint):
  28.  
  29.     var GetWindowText:function(hwnd:Longint;lpsz:PChar;cch:longint;id:Longint):Longint;
  30.  
  31.  2. Each function needs an identifier to distinguish the function from other called
  32.     functions. Declare this identifier in a var block.
  33.  
  34. For the above example:
  35.  
  36.     var id_GetWindowText:longint;
  37.  
  38.  3. In the initialization section of your application, set the 
  39.     address of the called function to the address of Call32:
  40.  
  41.     @GetWindowtext:=@Call32;
  42.  
  43.  4. Also in the initialization section of your application,
  44.  declare the actual library and name of the function you 
  45.  want to call with the Declare32 function. Pass it the name
  46.  of the function (CASE SENSITIVE!!!), the library name, and
  47.  a string describing the argument types. 
  48.  
  49.  Each letter in the string declares the type of one argument,
  50.  and should be either "i" for a 32-bit integer or handle
  51.  type, "p" for any pointer type, or "w" for an HWND parameter
  52.  to which you want to pass a 16-bit HWND and have it be
  53.  automatically converted to a 32-bit HWND. Save the return
  54.  value of Declare32 in a global variable to pass as the last
  55.  parameter to the function you declared earlier. So, in
  56.  continuing the example, you would call:
  57.  
  58.    id_GetWindowText:=Declare32('GetWindowText','user32','wpi');
  59.  
  60.  (As a side note, this more properly would be declared as
  61.  'GetWindowTextA', since this is the real exported name.
  62.  However, Declare32 will automatically add an 'A' to the
  63.  end of a function name if necessary.)
  64.  
  65.  To call the function, you would call:
  66.  
  67.    cbCopy:=GetWindowText(hwnd, sz, cb, id_GetWindowText);
  68.  
  69.  It is important to use the correct data types when calling
  70.  DLL functions. There are two important points to pay
  71.  attention to when using CALL32NT.PAS.
  72.  
  73.  First, only 32-bit integers can be passed to a DLL
  74.  procedure. Since virtually all 32-bit functions take int,
  75.  UINT, LONG, DWORD, or HANDLE parameters, which are all 32
  76.  bits, this is not a major restriction. However, you must
  77.  remember to always declare function arguments as Longint,
  78.  not Integer.
  79.  
  80.  Second, 16-bit handles and 32-bit handles are not
  81.  interchangeable. For example, a 16-bit bitmap handle that
  82.  you get from calling a 16-bit DLL or from the Delphi/TPW
  83.  environment cannot be passed to a 32-bit function
  84.  expecting a bitmap handle. Similarly, a 32-bit handle
  85.  obtained from a 32-bit function cannot be passed to a 16-
  86.  bit DLL. The only exception is window handles (HWND). If
  87.  you declare a function parameter with the "w" letter in
  88.  the argument description string passed to Declare32, the
  89.  corresponding parameter will be automatically converted
  90.  from a 16-bit HWND to a 32-bit HWND when the call is made.
  91.  You must still declare the argument as a LONG. This is
  92.  convenient, for example, when passing the value returned
  93.  by the "handle" property of a form/control to a 32-bit DLL
  94.  function. Only windows created by your application can be
  95.  translated.
  96.  
  97.  The following is a summary of data types:
  98.  
  99.  C data type    Type specified in Declare   Character for Declare32
  100.    int, UINT           Longint                   i
  101.    LONG, DWORD         Longint                   i
  102.    HANDLE              Longint                   i
  103.    WORD, short         not supported
  104.    HWND                Longint                   w (i for no 16->32 translation)
  105.    LPSTR               PChar                     p
  106.    LPLONG, LPDWORD,
  107.    LPUINT, int FAR *   VAR x:Longint             p
  108.    LPWORD              VAR x:Word                p
  109.  
  110.  Note on Declare32 function names: Declare32 will
  111.  automatically try three different names for the function
  112.  name you pass in. First, it uses the exact name you pass
  113.  in. If it doesn't find that function name, it converts the
  114.  name to the stdcall decorated name convention by adding an
  115.  underscore at the beginning and adding "@nn" at the end,
  116.  where "nn" is the number of bytes of arguments. If it
  117.  doesn't find that name, it adds an "A" to the end of the
  118.  original name to try the Win32(R) ANSI function calling
  119.  convention.
  120.  
  121.  If there occurs an error in Declare32, the returned id will
  122.  be less than 0. Also, the variable Call32NTError will be set,
  123.  so you only have to check one variable to check that all went
  124.  well. You can use this variable to distinguish between Windows
  125.  3.1 and Windows NT/95: if Call32NTError is false, you can use
  126.  the declared 32-bit functions, otherwise you must use 16-bit
  127.  replacement functions.
  128.  This allows you to write programs which work in both 16 and 32
  129.  bit environments.
  130.  
  131.  If you have to pass a record containing a pointer, you must use
  132.  the function GetVDMPointer32W to create a 0:32 pointer from
  133.  your 16:16 pointer.
  134.  
  135.  This unit is, like the original DLL, in the public domain.
  136.  Feel free to redistribute as you wish. No guarantees are 
  137.  made as to its suitability or usefulness, and no support
  138.  is provided. Please send bug reports to my CIS address
  139.  100332,1175.
  140.  
  141.  CALL32NT requires the Microsoft Windows NT operating system
  142.  or Windows 95 Preview or later to perform its task. The program
  143.  will also run in Win 3.1, but of course the functions will not
  144.  work.
  145.  
  146.